@boxpdf/html-writer 0.1.18 → 0.1.21

package/README.md

@@ -23,6 +23,23 @@ try {
 }
 ```
 
+For LLM and text-oriented workflows, stream Markdown from the same semantic
+document inference without generating HTML first:
+
+```ts
+import { writeMarkdownDocument } from "@boxpdf/html-writer";
+
+await writeMarkdownDocument(pdf.pages(), write, {
+  semanticLookaheadPages: 4,
+  imageOptions: "excluded",
+});
+```
+
+Markdown preserves inferred headings, emphasis, lists, tables, preformatted
+blocks, and grouped content. It uses the same bounded lookahead, table merging,
+repeated-furniture suppression, image options, and semantic statistics as
+semantic HTML.
+
 The default `visual` profile preserves page dimensions and text coordinates for
 display presentation. The `semantic` profile uses inferred reading order,
 lines, nesting, and tables to produce reflowable HTML. The visual model comes
@@ -50,10 +67,30 @@ The reported statistics also include processed pages, peak buffered lines, and
 suppressed furniture. Page-level `pageToHtml()` remains available when no
 cross-page inference is wanted.
 
+Semantic HTML excludes images by default, which keeps extraction output small
+for text and LLM workflows. Choose how raster and vector media are represented
+with `imageOptions`:
+
+```ts
+await writeHtmlDocument(pdf.pages(), write, {
+  profile: "semantic",
+  imageOptions: "references",
+  async onImage({ name, mimeType, data }) {
+    await saveAsset(name, mimeType, data);
+  },
+});
+```
+
+`"embedded"` writes raster data URIs and inline SVG into the HTML.
+`"references"` writes deterministic asset names into the HTML and passes each
+asset to the awaited `onImage` callback, so callers can store it without
+accumulating a document's images in memory. `"excluded"` omits media. Visual
+HTML defaults to `"embedded"`; semantic HTML defaults to `"excluded"`.
+Referenced semantic assets include both raster images and SVG vector media.
+
 The legacy `layout: "positioned" | "flow"` option remains as an alias for
-`profile: "visual" | "semantic"`. The current visual output surface excludes
-images, vector graphics, and exact font reproduction; the PDFium parity report
-tracks progress toward complete display presentation.
+`profile: "visual" | "semantic"`. The PDFium parity report tracks progress
+toward complete display presentation.
 
 The callback is awaited for every chunk, so a file stream, HTTP response, or
 Web `WritableStream` can apply backpressure. The caller owns and closes the PDF
@@ -69,11 +106,11 @@ Poppler's `pdftohtml -c -hidden -noframes -zoom 1` output. Poppler serves as an
 independent test oracle. The writer's memory contract covers the reader and
 HTML serialization.
 
-`pnpm poppler:report` runs the visual writer over all 62 text fixtures in
-the pinned PDF.js corpus. The checked-in baseline currently records exact text
-and geometry agreement on 51 fixtures. The remaining cases are retained in the
-denominator; most exercise intentional PDF.js/Poppler differences in RTL text,
-font encodings, or malformed Unicode maps. `pnpm poppler:gate` rejects any loss
+`pnpm poppler:report` runs the visual writer over every text fixture in the
+pinned PDF.js corpus. Cases where visual glyph rendering intentionally replaces
+extractable HTML text remain explicit in the baseline, alongside known
+PDF.js/Poppler differences in RTL text, font encodings, and malformed Unicode
+maps. `pnpm poppler:gate` rejects any loss
 from the known-good pass set and runs in CI.
 
 The writer retains the reader's logical Unicode order. RTL spans and flow lines